A general framework for epidemiological agent-based models:
Lightweight
Built on the C++ standard library.
Easy to port to other languages (R, Python).
A Framework
Highly modular.
User-defined states and update dynamics.
Fast
Out-of-the-box parallelism.
Up to 100 million agents-day per second.
Complex
Multi-virus.
Evolving virus.
Heterogeneous populations.
Various built-in models, including:
Susceptible-Infected-Recovered [SIR].
Susceptible-Exposed-Infected-Recovered [SEIR].
Susceptible-Infected-Susceptible [SIS].
Susceptible-Infected-Recovered-Decesed [SIRD].
…
Networked and non-networked versions.
About the software: research
We built epiworld to support our research in epidemiological agent-based models:
Meyer, Derek and Vega Yon, George (2023). epiworldR: Fast Agent-Based Epi Models. Journal of Open Source Software, 8(90), 5781, https://doi.org/10.21105/joss.05781
// Creating the model1Virus<> flu("Flu");2flu.set_incubation(5.0);flu.set_prob_infecting(0.2);flu.set_prob_recovery(1.0/7.0);// Adding mutation3flu.set_mutation(flumutates);// How will it be distributed 4flu.set_distribution( distribute_virus_randomly<>(20,false));// Adding the virus to the model5flu.set_state(1,3);model.add_virus(flu);
1
Create a new virus.
2
Define the virus parameters.
3
Define a mutation function.
4
Define how the virus will be distributed.
5
Add the virus to the model.
Demo: Mutating virus
Phylogeny of the flu variants. Each node represents a flu variant colored and sized by the transmission rate (larger+more orange = more transmissible).
Demo: Non-pharma intervention
1EPI_NEW_GLOBALFUN(full_isolation,int){// Getting new exposed from the model m->get_db().get_today_transition_matrix(tmatrix);int new_exposed = tmatrix[4];// Applying the policyif(new_exposed >1000) m->set_param("Contact rate",0.3);if(new_exposed <100) m->set_param("Contact rate",10);}2model.add_globalevent(full_isolation,"Full isolate",-99);
1
Design the intervention.
2
Add the intervention to the model (-99 = runs daily).
Demo: Non-pharma intervention
Daily incidence of the flu variants. Each line represents a flu variant colored by the transmission rate. The NPI is triggered when the daily cases are above 1,000 and cools down when below 100.
Demo: Speed-wise
This experiment (200 K agents for 180 days) took 1 second to run. As a reference, here is a comparison with other tools (different model):
Simulated a network SIR with 50 K agents:
Covasim (Python): ~ 1 second (although the model is more complex, SIRd).
Epiworld is 3x faster than igraph, 14x faster than AnyLogic, and 28x faster than ABM.
Demo: Full code
#include "epiworld.hpp"usingnamespace epiworld;// Some constantsconststaticdouble p_mutate =0.001;conststaticint max_int =std::numeric_limits<int>::max();EPI_NEW_MUTFUN(flumutates,int){if(p_mutate > m->runif()){// Creating new random sequence and updating// transmission probabilitydouble new_pinfect = m->runif()*0.7; v.set_sequence(static_cast<int>(new_pinfect * max_int)); v.set_prob_infecting(new_pinfect); v.set_name("flu-variant-"+std::to_string(new_pinfect));returntrue;}returnfalse;}std::vector<int> tmatrix;EPI_NEW_GLOBALFUN(full_isolation,int){ m->get_db().get_today_transition_matrix(tmatrix);int new_exposed = tmatrix[4];if(new_exposed >1000) m->set_param("Contact rate",0.3);if(new_exposed <100) m->set_param("Contact rate",10);};int main(){// Initializing one of the existing models.// In this case, network SEIR. epimodels::ModelSEIRCONN<> model("Covid-19",2e5,// Population size0.0001,// ~20 cases10,// Contact rate0.3,// Transmission rate7.0,// Mean incubation1.0/7.0// Recovery rate);// VIRUS DESIGN -------------------------------- Virus<> flu("Flu"); flu.set_incubation(5.0); flu.set_prob_infecting(0.2); flu.set_prob_recovery(1.0/7.0);// Adding mutation flu.set_mutation(flumutates);// How will it be distributed flu.set_distribution( distribute_virus_randomly<>(20,false));// Adding virus to the model flu.set_state(1,3); model.add_virus(flu);// Tool design ---------------------------------- Tool<> vaccine("Vaccine"); vaccine.set_transmission_reduction(0.3); vaccine.set_recovery_enhancer(0.9); vaccine.set_distribution( distribute_tool_randomly<>(0.3,true)); model.add_tool(vaccine);// Designing intervention: isolation -------------------- model.add_globalevent(full_isolation,"Full isolate");// Running the model model.run(180,221); model.print();// Saving the data model.write_data("res/virus_info.tsv","res/virus_hist.tsv","res/tool_info.tsv","res/tool_hist.tsv","res/total_hist.tsv","res/transmissions.tsv","res/transitions.tsv","res/repnum.tsv","res/gentime.tsv");return0;}
Final thoughts
Final thoughts
epiworld is a fast C++ library for epidemiological agent-based models.
Actively developed and featured in various Epi ABM studies.
User-friendly versions exist for R and Python.
It’s a framework: you can define your own states and update dynamics.